/**
Provides classes for implementing search services integrated to Lumis Portal.
<h2>1. Introduction</h2>
This package contains classes that can be used to implement ways to portal services index their
data, in order to search for this data later, based on user-entered criteria. In other words, these
classes compose an extensible search engine architecture, to be used by portal projects based on
Lumis Portal.
<p>
Lumis Portal comes with an implementation of search engine based on 
<a href="http://lucene.apache.org">Apache Lucene</a>. It's the default search engine used. Portals
based on Lumis Portal have a configuration that allows the use of one or more compatible search
engines to index and search for services data.
<p>
When you have data that needs to be searchable, it has to be indexed first. The indexing process is done 
by an {@link lumis.search.Indexer} implementation. Then, later, when, for example, an user requests a
data search, a search is executed by a {@link lumis.search.Searcher} implementation. 
<p>
<h2><a name="concepts">2. Main Concepts and Classes</a></h2>
<p>
<h3><a name="searchableinfo">2.1. Searchable Information</a></h2>
<p>
A searchable information is any textual information that can be stored by a search engine and later
be found by some textual criteria such as keywords and text fragments.
<p>
Portal services can deal with several kinds of information, such as news, articles, images and
files. Any kind of information can be considered "searchable" once it has some textual portion.
For example, a news is a typical textual content and obviously searchable. In other hand, an image
can considered "searchable" only if it has some aggregated textual information, such as
image authoring or description. A file will be searchable only if its format allows text
extraction.
<p>
Once the textual searchable information was given or extracted from original information, it can
be indexed and searched using the infra-structure present in this package.
<p>
A searchable information is encapsulated in a {@link lumis.search.SearchContent} object.
<p>
<h4><a name="searchcontentfields">2.1.1. Fields</a></h2>
<p>
A searchable information is composed by one or more fields, each of them having a name and one or
more string values.
<p>
A field is represented by a {@link lumis.search.SearchContentField} object.
<p>
There are five predefined field types:
<ul>
<li>{@link lumis.search.SearchContentField#FIELDNAME_ID Identifier}: identifies the information;
<li>{@link lumis.search.SearchContentField#FIELDNAME_TITLE Title}: title of the information;
<li>{@link lumis.search.SearchContentField#FIELDNAME_SUBTITLE Subtitle}: subtitle of the information;
<li>{@link lumis.search.SearchContentField#FIELDNAME_URL URL}: URL to the information details;
<li>{@link lumis.search.SearchContentField#FIELDNAME_TEXT Text}: searchable text of the information.
</ul>
<p>
<h3><a name="searchengine">2.2. Search Engine</a></h2>
<p>
A search engine is a subsystem that provides indexing and searching functionality to the portal
infra-structure.
<p>
Basically, a search engine is a set of implementations for {@link Indexer} and {@link Searcher}
implementations that has a configuration section in the <a href="#configfile">configuration
file</a>.
<p>
The default search engine that comes with Lumis Portal is an implementation based on 
<a href="http://lucene.apache.org">Apache Lucene</a>, a popular Information Retrieval framework
that stores searchable information on indexes in the file system.
<p>
Custom search engines can be implemented to integrate a portal solution to other search engines and
IR frameworks.
<p>
<h3><a name="indexing">2.3. Indexing</a></h2>
<p>
Indexing is the action of storing a searchable information, in a way that allows to find this
information using text search criterias, such as keywords or information fragments.
<p>
A typical data indexing cycle is composed by the following steps:
<ul>
  <li>A <a href="#searchengine">search engine</a> is selected, based on portal 
  		<a href="#configfile">configuration</a>;</li>
  <li>A {@link lumis.search.SearchContent} object, that contains one or more 
  		{@link lumis.search.SearchContentField} objects, is populated with the data;</li>
  <li>An implementation of {@link lumis.search.Indexer}, related to the selected 
  		<a href="#searchengine">search engine</a>, is instantiated;</li>
  <li>The {@link lumis.search.SearchContent} object is indexed using 
  		{@link lumis.search.Indexer#addSearchContent(SearchContent)}.</li>
</ul>
<p>
Some search engines can pre-process the information before it is stored, to perform some common
actions, like case normalization, common words cleaning etc.
<p>
A search engine provides indexing functionality through an implementation of the
{@link lumis.search.Indexer} class, that receives the searchable information to be indexed in
a {@link lumis.search.SearchContent} object, which has a collection of
{@link lumis.search.SearchContentField} objects.
<p>
<h3><a name="searching">2.4. Searching</a></h2>
<p>
Searching is the action of find an information based on a certain criteria, usually a portion of
the original information. This portion can be a keyword given by the user or any fragment of
information that can be used to match one or more previosly indexed informations.
<p>
A typical search cycle consists in the following steps:
<ul>
  <li>A <a href="#searchengine">search engine</a> is selected, based on portal
  		<a href="#configfile">configuration</a>;</li>
  <li>A {@link lumis.search.SearchQuery} object is populated with the user-entered search 
  		criteria;</li>
  <li>An implementation of {@link lumis.search.Searcher}, related to the selected 
  		<a href="#searchengine">search engine</a>, is instantiated;</li>
  <li>The data is searched using the {@link lumis.search.Searcher#search(SearchQuery)} method;</li>
  <li>The search results are returned in a {@link lumis.search.SearchResults} object, that contains
   		one {@link lumis.search.SearchHit} object for each result that matches the criteria.</li>
</ul>
<p>
Some search engines, like the default search engine, provide advanced features that can be used
in search criterias, such as wildcards and boolean operators.
<p>
A search engine provides searching functionality through an implementation of the
{@link lumis.search.Searcher} class, that receives the search criteria in 
a {@link lumis.search.SearchQuery} object. The search results returns from the search engine in a
{@link lumis.search.SearchResults} object, which has one {@link lumis.search.SearchHit} object for
each searchable information that matches the given search criteria.
<p>
<h2><a name="configfile">3. The Search Configuration File</a></h2>
<p>
The Lumis Portal's search infra-structure can be configured using the configuration file
<code>searchconfig.xml</code>, that can be found in the <code>lumisdata/config</code> directory. 
<p>

 * @version $Revision: 10348 $ $Date: 2009-04-13 17:31:28 -0300 (Mon, 13 Apr 2009) $
 * @since 4.0.4
 */
package lumis.search;